-
Notifications
You must be signed in to change notification settings - Fork 76
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Dont show invalid sbt and scalajs versions #614
Dont show invalid sbt and scalajs versions #614
Conversation
template/src/main/twirl/ch.epfl.scala.index.views/search/resultList.scala.html
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have a few small suggestions, but other it looks good to me. Did you pre-deploy these changes so that we can test them?
model/src/main/scala/ch.epfl.scala.index.model/SemanticVersion.scala
Outdated
Show resolved
Hide resolved
model/src/main/scala/ch.epfl.scala.index.model/SemanticVersion.scala
Outdated
Show resolved
Hide resolved
It is deployed to http://index-dev.scala-lang.org |
Thanks! Looking at https://index-dev.scala-lang.org/search?q=*&scalaJsVersions=1, I suspect there might be something wrong. There are definitely a lot more than 9 libraries with support for Scala.js 1.x. Also, could we display Scala.js 1 as |
There is only 9 scala.js 1.x libraries because I have reindexed an old snapshot dating 2017. Reindexing the entire database will be much longer but I will try that in a few moments. The scala.js version comes from the name of the artifact (e.g. |
Hum, then that means that it is still indexing libraries for milestones/RCs of 1.0.0. We'd like those not to be indexed anymore, as it is not useful, and it is actually downright misleading to say that they support 1.x, because support for 1.0.0-Mx or 1.0.0-RCx does not guarantee support for 1.0.0+.
When we talk about Scala.js 1.x, we always talk about 1.x. Nobody writes Scala.js 1. It doesn't really matter what the encoding of artifacts is. What matters for display is how people talk about the version number. So IMO 1 is more confusing than 1.x. |
@sjrd you are right about the milestones and RCs of scala.js 1.0.0 being indexed. I need clarification on this: what do we do with future milestones and RCs of scala.js 1.1? Do we include them in 1.x or do we separate them in a 1.1 version? This issue is not specific to scala.js: see #526 for scala jvm. I'll treat them both here. And what about scala native? Should we display all versions from 0.1 to 0.4? |
Also, I am afraid that the reindexing of the entire database does not work. It has been stuck since yesterday 9pm. I have to work on that too before merging. |
The general rule for me would be: only index a milestone or RC if it is the very latest available version. That means that:
This general rule seems to work well for all the cases I can think of. In addition to that, for stable releases, only index the following versions IMO:
If the binary version is different, the ecosystem is different, so you must consider that a separate version. If the binary version is the same (e.g., Scala.js 1.1.0 will also use the binary version All you need to care about is the binary version. This is the source of truth. That is true for the JVM, for JS, for Native and for sbt. No exception. |
I am not clear about the meaning of "binary" in "binary version". Does it mean "binary compatibility"? As far as I know, the rules of "binary compatibility" are not the same in Scala JVM and Scala.js, since 2.12 and 2.13 are not compatible but scala.js 1.0 and 1.1 should be compatible, right? It's even more complicated than that because sjs 0.5 is not compatible with sjs 0.6 and sjs 1.0.0-M2 is not compatible with 1.0.0. |
When you parse the artifact names, all you ever get is the binary version. When you see So in Scaladex all you ever see is the binary version, since you cannot determine the full version (you can't tell from And as soon as two binary versions are different, they create entirely different and incompatible ecosystems. So Scaladex should never try to be "smart" and collate together "similar" versions. No, if Scaladex sees two different (even if "similar") versions, they really are different, and must never be lumped together in the same bag. |
Alright then. I like your point of view. Scaladex used to truncate binary version |
The only reason you'd see a binary version like How to deal with compiler plugins, I am not sure. My hunch is that you can just not index them. They are often accompanied by a genuine library anyway or by an sbt plugin, so that would be their entry point in Scaladex. For compiler plugins that are really just compiler plugins (and I can't name one off the top of my head), they would not be indexed, but I think that's fine for now. We can reconsider later if we need to find a solution for them. So concretely, you can ignore "invalid" binary versions. Valid binary versions are:
|
One more precision: so far every artifact is indexed even if it's target type is considered obsolete or invalid. I will keep it that way for the moment. My goal is to discard invalid versions from the front page, the result list and the dropdown list of a project. |
Are you sure about JS |
d764563
to
7949a4d
Compare
7949a4d
to
a04a5f1
Compare
Here it comes ==> https://index-dev.scala-lang.org/ |
model/src/main/scala/ch.epfl.scala.index.model/release/ScalaTarget.scala
Outdated
Show resolved
Hide resolved
654af25
to
5a53709
Compare
5a53709
to
e882e10
Compare
Only push 1 commit if doing a feature branch release Fix output of job so we can get the release_type Updating a tag requires force-pushing, and that feels bad Comment on PR when a preview release is published Remove troublesome backticks that confuse bash... Ideally we would be generating a markdown message with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ### Problems with backticks ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters
Only push 1 commit if doing a feature branch release Fix output of job so we can get the release_type Updating a tag requires force-pushing, and that feels bad Comment on PR when a preview release is published Remove troublesome backticks that confuse bash... Ideally we would be generating a markdown message with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ### Problems with backticks ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters
Only push 1 commit if doing a feature branch release Fix output of job so we can get the release_type Updating a tag requires force-pushing, and that feels bad Comment on PR when a preview release is published Remove troublesome backticks that confuse bash... Ideally we would be generating a markdown message with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ### Problems with backticks ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters
Only push 1 commit if doing a feature branch release Fix output of job so we can get the release_type Updating a tag requires force-pushing, and that feels bad Comment on PR when a preview release is published Remove troublesome backticks that confuse bash... Ideally we would be generating a markdown message with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ### Problems with backticks ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This addresses #10, providing support for publishing *preview* releases based off feature branches, ie PRs. The UX of doing a preview release is very similar to the existing process for doing a full release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md), with only these differences: * The developer needs to select the PR branch before clicking the green `Run workflow` button * The version number will be the **upcoming** version number, but with a suffix that clearly indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`. Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT` releases. * No branches are updated by the release (ie, not the PR's feature branch, and not the default `main` branch) - the preview release commit exists as its own tagged commit, taking the latest PR commit as its parent. * GitHub release notes will not be created, but instead the PR using that branch will be updated with a comment providing details of the new release (version number, etc). Internally, these 'preview release' changes take place if a non-default branch (ie a feature branch, not `main`) is used: * The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH` * Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed by the full release process (incrementing the version number and adding the `-SNAPSHOT` suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW` version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR. * When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation message including the hashes of all artifact files generated by the release, and at the point when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use a new, different, disposable, Git tag instead. ## Choice of version-suffix for preview releases https://semver.org/#spec-item-9 says: > 9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. > > 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. ### How can we prevent tooling from thinking our preview releases are stable releases? If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them. * IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview' * Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc * Scaladex uses PreRelease.scala - scalacenter/scaladex#614 Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number: * 'PREVIEW' * a commit hash of at least 8 characters ### NPM version numbers... Some Guardian libraries are released simultaneously for both Scala and other platforms like NPM (for instance, `content-api-models`, see guardian/content-api-models#229). Both NPM and sbt/Maven work well with simple three-number semver version numbers, but how well will NPM handle extended version number like `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4` ? ### 'PREVIEW', 'BETA', 'ALPHA', or...? Justin points out the 'PREVIEW' has a particular meaning for the Content Pipeline team ('Preview' vs 'Live' content) - could potentially cause some confusion there. I initially chose 'PREVIEW' (from the identifiers that IntelliJ & Scala Steward understand) partially because both 'BETA' & 'ALPHA' imply some meaning about the stage of development in the software release cycle that may or may not be appropriate - it's not obvious which one truly reflects what we're doing when we make an early release from a PR, and it's annoying to have to choose. Additionally, looking at the Wikipedia article that describes the different stages - the label 'pre-alpha' might even be more appropriate: https://en.wikipedia.org/wiki/Software_release_life_cycle ## Problems with backticks Ideally we would be generating a markdown message for the PR comment with lots of backticks for styling: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks ...like this: rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment) ...but they get interpreted by BASH, and cause trouble... https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058 ...so for the time being this PR avoids them in the generated PR comment.
This PR is deployed to https://index-dev.scala-lang.org
First commit
Second commit
Third commit